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START - UP 



TO START UP: 



Put the OSS diskette in disk drive 1. Enter : 

6 control-P (return) 
This will load the Operating System and execute CP/A. Now enter : 

BASIC (return) 
This will load the Basic and start executing it. When the 

READY 

appears on the screen* the user may begin. 



If the user goes to the Apple II (R) monitor after start-up* he 
can return to Basic by entering : 



This will perserve the user's statements already in memory. It 
will also leave the current low and high memory addresses unchanged. 

The user can return to CP/A using the Bacis command CP. He can 
then re-enter Basic by using the CP/A command RUN (if he has not 
loaded another program). This does a warm start. 



To make a back-up copy of Basic on another diskette* use the CP/A 
SAVE command. 



WARM START: 



control-Y 



(return ) 



BACK-UP COPY 



Start address 
End address 
File name 



8000 
A800 

BASIC. COM 



NOTE: For a full explanation of CP/A commands* see the Control 
Program/Apple documentation. 



STATEMENTS AND FUNCTIONS 



SYNTAX CONVENTIONS 

The following conventions are used in this manual. 

1- Capital letters denote keywords, etc. , which must be typed 

by the user exactly as shown <e. g. PRINT. RUN) . 

2. Lower case letters denote the types of items which may be 

used. The various types are shown on the next page. 
< e. g. , avar > sexp ) 

3- Items enclosed in square brackets (e.g., C,var3) are optional. 

4 - Items enclosed in square brackets together with ellipses imply 
that the item shown may repeated any number of times, (thus 

C» exp. . . 3 is e qui van t to C, exp, exp, exp. . . 3, etc.). 

5- Multiple items in braces indicate that any one may be used, 
(e.g. {END > implies END and STOP are equivalent statements). 

■CSTOP} 
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TYPES OF ITEMS 



The following types of items ere used in decribing the syntax of state 
ments and functions: 



GENERAL ITEMS: 
avar 



Arithmetic VARiable, a storage location for a numeric value. 
Variable names are 1 to 16 alphanumeric characters and must 
start with an alphabetic character. 



Example: 



TOTAL 



C0UNTER3 



svar String VARiable, a storage location for a string of characters 
(bytes). Same name rules as "avar" except last character must 
be a dollar sign <"*") which is included in the count of char- 
acters in the name. 



Example: 



NAME* 



ADDRESS* 



mvar Matrix VARiable, an element of an array (matrix) of numeric 
values. The name of the matrix is similar to a string vari- 
able name except that the last character must be a left parent 
hesis. 



asvar 



Examp 1 e: 



COUNT (NUM) 



'avar" or 



svar' 



indicates the NUMth 
element of the array 

COUNT. 



var 



VARiable, any of "avar", "svar" or "mvar" 



aop The arithmetic operators 

+ -*/** 

(+ and - can be unary or binary operators) 

lop The logical operators 

<<»>>»<>- 
AND NOT OR 



lexp 



sexp 



(NOT is an unary operator) 

Logical Expression, generally composed of "aexp lop aexp" or 
"sexp lop sexp"i a logical expression evaluates to "true" 
(represented numerically by a constant 1) or "false" 
(numerically, 0). 



Example: 



1<2 is true, "CAT" ■ "DOC" is false. 



String Expression, can consist of a string variable, string 
literal, or a function which returns a string value, No 
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operators are allowed in a sexp. 



Example: ADDRESS* 

"SMITH, JOHN" 
CHR*<41 ) 



aexp an Arithmetic EXPressioni generally composed of "aexp aop 
aexp" recursively where each aexp element may be an "lexp" 
"avar", "mvar", numeric literal, or arithmetic function. 
The arithmetic expression may start with an unary operator. 

Example: -A+3 

2*SIN(30> 

7+INT(B) 

A*>B$ 

exp Either "aexp" or "sexp" 

linenum An expression which is rounded to an integer value. Must 
be between 1 and 32767. 

FILE ITEMS: 

*n file number, an aexp that is rounded to the nearest integer 

and must be in the range 1 to 7. 

filspc decribed under I/O statements. 

mode an aexp which indicates type of I/O to be performed on a file. 
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EXECUTION CONTROL STATEMENTS 



GOTO linen urn 

GOTO transfers execution to the line at "linenum" It can also 
be written GO TO. 

GOSUB linenum 

GOSUB calls a subroutine which begins at "linenum". 

RETURN 

RETURN transfers execution to the next statement after the last 
executed GOSUB. 

ON aexp <GOTO > linenum C# linenum. .. ] 
■C GOSUB > 

ON first evaluates aexp and rounds the result to the nearest 
integer. Then executes a GOTO (or GOSUB) to the 1st linenum in 

the list if the value is 1, the 2nd if the value is 2/ etc. 

If the value » or is > the number of linenum's in the list* 

then control falls through to the next line. 

IF aexp THEN {statement} 
{linenum > 

If aexp is "true" (evaluates to non-zero>> the statement follow- 
ing the THEN (and any subsequent statements on the line) is/are 
executed. 

If aexp is "false" (evaluates to zero), then control passes to 
the next sequential line. 

The form "THEN linenum" is equivalent to "THEN GOTO linenum". 

Example: 1000 A=3: D=4: C=3 

2000 IF A=B THEN PRINT "X":PRINT"Y" 
3000 PRINT "Z" 

Since A«B is false, executing line 2000 mill cause 
control to pass to the next line and will print: 
Z 

(Y will not be printed. ) 

Example: 1000 A«3: B=4: 03 

2000 IF A*C THEN PRINT "X": PRINT "Y" 
3000 PRINT "Z" 
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Executing this program mill cause the print out: 

X 

Y 

Z 



FOR avar ■ aexpl TO aexp2 CSTEP aexp33 
NEXT avar 

When FOR is executed, avar is given the value aexpl. 
When NEXT is executed. aexp3 (which takes the value +1 if not 
given) is added to avar. If avar is then less than or equal 
to aexp2. control passes to the statement following the FOR, 
else control falls through to the statement after NEXT. 

NOTE: All loops execute at least once. 

"aexp3" may be positive or negative, 
"avar" is required for NEXT. 
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MISCELLANEOUS STATEMENTS 



POP 

POP causes the information about the last GOSUB or FOR to be 
discarded. 

Example: 1000 GOSUB 2000 

1100 PRINT "HELLO" 
1200 END 
2000 GOSUB 3000 
2100 PRINT "NO WAY" 
2200 STOP 

3000 PRINT "THIS IS A TEST" 
3100 POP 
3200 RETURN 

In this example, the POP at line 3100 will discard 
information about the last GOSUB (the one at 2000). 
Then executing the RETURN at 3200 will cause control 
to pass to line 1100. Executing the program causes 
this print out: 

THIS IS A TEST 
HELLO 



DIM svar(aexp) 
DIM mvar(aexp) 
DIM mvar (aexp> aexp ) 

DIM lets the user declare the "size" of a string or array. 
First, aexp is evaluated and rounded to the nearest integer 
value. 

When the parameter is svar the value is the number of char- 
acters in the string. 

When the parameter is mvar, the value is the largest subscript. 
Since the smallest value is 0, there will be value+1 elements 
in the aTraii. 

Arrays may be two dimensional. 

NOTE: Multiple strings or arrays may be dimensioned in the 
same DIM statement. 

Example: DIM A<3,2>, B*<7>, C(3) 

This defines a 4 by 3 array whose last element is 
A<3, 2), a string with 7 characters, and an array with 
4 elements: C<0), C<1), C(2), C<3). 

NOTE: All string and arrays must be DIMensioned before being 
used. Attempting to access an element or character 
outside of the size will cause an error. So will 
attempting to access a string or array that has not 
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been DIMed. 



NOTE: 

DIM does not zero array or string elements. The 
user may do this with a FOR/NEXT loop. 



NEW 

NEW erases the current program and all references to variables 
from memory. 



CLR 

CLR zeros all variables and undimensions all arrays and strings 

NOTE: CLR does not zero the memory used by strings and 
arrays. 



LOMEM aexp 

The aexp is evaluated and rounded to nearest integer. This 

value is set as the new LOMEM address (the address at which 

the user tables start). Then a NEW is done. 

NOTE: LOMEM destroys any program currently in memory. 



REM ASCII characters 

REM denotes a remark or comment. It has no effect on execution 
of the program. The rest of the line is ignored. 



DEG 
RAD 

These statements only affect the trig functions (SIN. COS. ATN). 
When DEG is specified, the arguments of SIN and COS and the 
result of ATN are assumed to be given in degrees. When RAD 
is specified, these values are assumed to be in radians. 
The default for Basic is radians. 



CP 

CP returns control of the system back to the OSS Control 
Program. 



BYE 

BYE returns control of the system to the APPLE II (R) monitor. 



POKE aexpl. aexp2 
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"aexpl" and "aexp2" are evaluated and rounded to the nearest 
integer. 

Then the contents of the byte at memory location aexpl is 
changed to aexp2. 
O aexpl <« 65535 
O aexp2 <« 255 

Example: POKE 5000, 10 

This will cause location 5000 (decimal) to contain 
10 (decimal). 

NOTE: The function PEEK will allow the user to get a byte 
from a memory location. 

ASSIGNMENT STATEMENTS 



CLET3 svar ■ sexp 
CLETD <avar> ■ aexp 
<mvar> 

LET assigns the value of the expression on the right side of 
the equal sign to the variable element on the left side. 

Example: A*=CHR*(48) 

LET B(l, 2) » C+3 



READ asvar Z> asvar. . . D 

DATA ASCII characters I. ASCII characters. .. 3 
RESTORE Clinenuml 

These statements allow data to be stored and retrieved within 
the program body. 

READ takes the next parameter from a DATA statement (ASCII 
characters up to a comma) and assigns it to "asvar". 
If "asvar" is an "avar" then the ASCII characters must represent 
a numeric value. 

If "asvar" is a "svar" then the ASCII characters up to a comma 
are assigned to the string. 

RESTORE indicates the first DATA statement or the DATA state- 
ment at linenum. The subsequent READ will access that DATA 
statement for its parameters. 



INPUT Will be decribed in the next section. 
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INPUT/OUTPUT STATEMENTS 



FILE SPEC: 



Many I/O statements include a file specification (filspc). This file 
spec must be a string and have the following format. 

filspc - "dev : filename [.file extD" 

dev - <A> 
<B> 

A indicates a disk in slot 7 drive 1. 
B indicates the disk in slot 7 drive 2. 

For information on specifications for other devices see 
Operating System <OS> documentation. 

f i lename 

1-8 alphanumeric characters, the first being alpha. 

file ext 

0-3 alphanumeric characters. 

This file spec may be a literal string ( "A: ABCD. X " ) or a string 
variable which has previously been assigned the proper format 
<A* where A* = "B: ABC. XXX" ) . 

FILE NUMBER: 

In all I/O statements. #fn is a file number in the range 1 to 7. 
"fn" is given as an aexp which is rounded to the nearest integer. 
In statements where #fn is optional and is omitted, the I/O uses 
the keyboard for input or the screen for output. 

STATEMENTS: 

OPEN #fn. aexpl. aexp2. filspc 

OPEN prepares a file for access and assigns it the file number 
"fn". 

fn - file number C1-7D 
aexpl - I/O mode 
4 - input 

6 - directory access 

8 - output 

9 - append 
12 - update 

aexp2 - device dependent information or 0. 

NOTE: After OPENing a file, the file number is used to de- 
signate the file in other I/O statements. Two OPEN 
files cannot have the same file number. 
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Example: 



OPEN #2.4, 0, "A: DUT. SRC 



This will cause the file DUT. SRC on disk 1 to be 
opened for input and will associate file number 2 
with the file. 



CLOSE #fn 

CLOSE closes the file associated with the file number "fn". 

PRINT C#fn <i>3 exp C<»>exp. ..3 <> > 
•C, > <; > <; > 

PRINT puts the ASCII equivalents of the given expressions to 
the file specified (or the screen). sexp's are simply output 
(without any conversion — i. e. • the full 8-bit byte is output) 
from their beginning to their length. aexp's are converted to 
printable form. A comma causes "tabbing" to the next tabular 
column. A following semicolon causes no spacing. 

If the PRINT statement ends in a , or ; then a subsequent PRINT 
starts outputing at the last location* otherwise the next PRINT 
will start on a new line. 

Example: 100 DIM A*(10) 

200 A* » "VALUE =" 
300 A ■ 100 
400 PRINT A*, A 
500 PRINT A*; A 
600 PRINT A*i 
700 PRINT A 
800 PRINT A*; 
900 PRINT A 
1000 PRINT A* 
1100 PRINT A 
2000 END 

This program causes the following printout: 

VALUE- 100 
VALUE- 100 

VALUE- 100 

VALUE- 100 

VALUE- 

100 

NOTE: A "," after #fn causes tabbing before first character 
is printed. A "; " does not cause the tabbing. 



INPUT C#fn, 3 var I, var. . . 1 

INPUT requests ASCII input from the specified file number (or 
the keyboard). It uses a ? prompt. If a "svar" is specified, 
it accepts a string of characters without transformation until 
an end-of-line (carriage return) is dectected. 

For an "avar" or "mvar"# numeric data is converted to internal 
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form. 



NOTE: While numeric data can be terminated by either a comma 
or a carriage return, string data can only be ter- 
minated by a carriage return. So when input is coming 
from the keyboard and the "svar" is followed by another 
variable* the user must enter carriage return to end 
the "svar". Basic will then prompt the user with 
another ? for the next variable. 

Example: 1000 DIM A*(50> 

2000 INPUT A*» B 

When running this program Basic prompts the user with ?. 
IF the user enters: 

JONES. SALLY 

this becomes the value of A* and then Basic prompts 
again for the value of B. 



GET #fn. avar 



GET inputs a single byte from the file specified by "fn" and 
stores it in avar. 



PUT #fn, aexp 

PUT outputs a single byte <aexp) to the file specified by "fn". 



NOTE #fn. <avarl>. <avar2> 
•Cmvarl}* <mvar2> 

NOTE returns the current sector # and byte within the sector 
for the file specified by "fn". 

Current sector # is assigned to the first variable. 

Byte within the sector is assigned to the second variable. 



POINT #fn* -Cavarl>, <avar2> 
■Cmvarl >» -Cmvar2> 

POINT sets the current sector # and byte within the sector for 

the file specified by "fn". 

Current sector is set to 1st variable. 

Byte within sector is set to 2nd variable. 



STATUS #fn. *avar> 
<mvar> 

STATUS gets the status of the last I/O performed on device #fn 
and assigns it to the given variable. 



LIST tfilspc] 

LIST Cfilspc, D linenuml C.linenum23 



-12- 



LIST lists the program currently in memory to the screen (or to 
the file specified if "filspc" is given). 

If two linenum's are given, only the lines from linenuml to 
linenum2 (inclusive) are listed. If a single linenum is given, 
only that line is listed. 



ENTER filspc 

ENTER brings a program that was LISTed (ASCII source) back into 
memory from the specified file. Each statement is syntaxed as 
it comes in. 



SAVE filspc 

SAVE puts the program currently in memory to the file specified 
in an internal format (not in ASCII). 



LOAD filspc 

LOAD gets a program that has been SAVEd from the file specified. 
No syntaxing is done since the program is already in internal 
format. 



XIO cmd< #fn, aexpl, aexp2, filspcl 

XIO is used to specify various functions to a specific device 
handler. 

Currently this command allows the user to perform various 

functions on a disk or disk file. 

The value of "cmd" tells which function. 

cmd function 

32 rename (filspcl = dev: oldname, newname ) 

33 delete file 

35 lock 

36 unlock 

37 point 

38 note 

"fn" tells what file number to associate with the file for 
this operation. 

"aexpl" and "aexp2" are for the functions currently defined. 

"filspc" specifies the device and file. 

Example: XIO 33, #6< 0, 0, "A: NOGOOD" 

This will cause the file NOGOOD on disk 1 to be 
deleted. File number 6 will be associated with this 
file during the process. 
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NOTE: If the user has added his own device handler (see 
Operating System (OS) documentation), the XIO cmd 
can have special meaning to that handler. 
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PROGRAM CONTROL STATEMENTS 



RUN 

RUN filspc 

RUN without parameters causes the program currently in memory 
to start execution at the first line number. All variables are 
set to zero and all strings and arrays are undiminsioned (as if 
a CLR had been done). 

Entering : 

RUN filspc 
causes two commands to be executed: 

LOAD filspc 

RUN 

NOTE: In order to LOAD the file it must have be SAVEd 
<not LISTed). 



STOP 
END 

These statements cause the program to terminate. They are 
equivalent except that STOP prints out a message giving the 
current line number. 

NOTE: END is not required at the end of a program. 



CONT 

CONT allows program execution to continue after a STOP or END 
at the next line number (not next statement). 



TRAP linenum 

If an error is encountered after a TRAP statement has been 
executedi control is transfered to the routine at "linenum" 
This allows the user to have a routine to process errors. 

NOTE: TRAP can be disabled by giving a line number 
greater than 32767. 

(More information about error processing can be found 
in the Error section). 
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ARITHMETIC FUNCTIONS: 



ABS<aexp ) 
EXP(aexp) 



Returns absolute value of aexp. 



Returns exponential of aexp. 
Example: A ■ EXP(X) 

A will be assigned the value E^X where E«=2. 7182818. 



FRE(aexp ) 



Returns number of bytes of memory still avaiable. 
Aexp is a dummy argument. Its value has no effect. 



INT(aexp) 



Returns the next smaller integer. 



SQR(aexp ) 
LOG (aexp > 
CLOG (aexp ) 
RND(aexp ) 



Example: 



INTO. 8) returns 3 
INT(-3. 8) returns -4 



SGN(aexp) Returns an indication of the sign of the argument: 



+1 if aexp >0 
if aexp =0 
-1 if aexp <0 



Returns square root of aexp. 



Returns natural log of aexp. 



Returns common log (base 10) of aexp. 



Returns a pseudo-random number in the range O to 1 
If aexp is less than 0# the random number generator 
is reseeded before a value is returned. 



SIN(aexp) 
COS(aexp ) 
ATN(aexp) 



Returns sine of aexp. 



Returns cosine of aexp. 



Returns arc tangent of aexp. 



The statements DEG and RAD determine whether 
the argument/result is assumed to be in degrees 
or radians for the trig functions. The default 
is radians. 
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STRING FUNCTIONS / STRING RELATED FUNCTIONS 



LEN(sexp) 



Returns the current length (not DIM size) in bytes 
of the string argument sexp. 



VAL(sexp) 



Looks at the leading numerics in the string (up to 2S5) 
and returns their value as a number. 

Example: A - VAL ( " 57A6B " ) 

"A" will be assigned the value 57. 

Example: PRINT VALC'ABC") 

This will cause an error. 



ASC ( sexp ) 



Returns a number which is the ASCII equivalent of the 
first character in the string. 



Example: 



PRINT ASC ("A") 
65 (hex 41) 

PRINT ASCC'AB" ) 
65 

PRINT ASC("57A" ) 
53 (hex 35) 



prints: 
prints: 
prints: 



STR*(aexp ) 



Returns a string that looks like the PRINTed form of 
the aexp. 



Example: 



B* « STR*(352) 

has the same effect as 

B* « "352" 



CHR*(aexp ) 



Returns a one byte string that contains the value 
of aexp. 



Examp 1 e: 



PRINT CHR*(65) prints: 
A 



PRINT CHR*(53) prints: 
5 

PRINT CHR*(07) 
rings the bell. 

NOTE: CHR* function can be used to insert a byte of 
binary data into a string. In other words* 
"aexp" does not have to represent a printable 
ASCII character. 
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Example: DIM A*(10) 

A»( 1 )«CHR»(255) 
A»( 10)=CHR*( 13) 

This will insert hex FF as first character 
of string A* and hex OD (carriage return) 
as the last. 

NOTE: There can be only one STR* and only one 
CHR* in a string compare. 

Example: A - STR*(1) > STR*<2) 

produces unpredictable results. 

MACHINE ACCESS FUNCTIONS: 



PEEK(aexp ) 

Converts aexp to an integer value by rounding. It returns 
the contents of the byte in memory at that value. 
(Memory can be altered by the POKE statement). 



Example: memory location value 

(decimal) (decimal) 

5000 1 

5001 128 

5002 25 



A « PEEK (5001) assigns value 128 to A 



ADR(svar) Returns the address of a string in memory . 



USR (aexpl C, aexp2. . . 3 ) 

Evaluates the expressions and rounds to the nearest 
integer. It pushes the integer values "aexp2" on the 
CPU stack and puts the number of arguments in the 
accumulator. It then calls the machine language 
subroutine at address "aexpl". When Basic regains 
control* it uses the value in floating point register 
(FRO) (see memory map address) as the function value. 

NOTE: Use with carei this can be a dangerous function 
if used improperly. 

(For a more detailed explaination see section on 
USR function). 
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GENERAL INFORMATION 



Any given line may contain multiple statements separated 
by colons. 

A program that is executing can be stopped by hitting the escape 
key (ESC). LIST can also be stopped in this manner. 

Since CONTinue causes the program to start executing 

at the next line (not statement), STOP and END should generally 

be the last statements on a line. 

EXAMPLE: 1000 REM TEST PROGRAM 

2000 A=l. STOP: PRINT A 
3000 END 

The "PRINT A" in the program can never be executed since 
CONT entered after the STOP will cause the program to start 
at line 3000. 

Entering a line number and then a carriage return 
deletes the line. 



KEY WORDS 



All statement and function names plus TO, STEP/ THEN, 
AND* NOT, and OR are Basic's key words. 

For clarity, key words should not be used as a prefix 
in variable names. 

Blanks are significant characters to Basic and key 
words must be preceeded and followed by blanks any time an 
ambiguity would result. 

During syntaxing the scan is left to right. If Basic 
is looking for a keyword next, it will stop as soon as it 
has found one regardless of the next character. Thus 

FORI - 1 TO 3 
is valid syntax. 

Example: FOR K = ATOB 

A = BAND X 
Cause syntax errors. 

FOR K ■ 1T02 
A » B +3 
OOTO 1000 
1000IFI-3THEN100 
Are all valid syntax. 



SYNTAX I NG AND INTERNAL FORMAT 



Statements are syntaxed on entry. Space for variables 
is allocated at entry time (not run time). Lines are saved 
in an internal (tokenized) format. 

In this format: 



Each variable and/or reserved word in a program mill 
occupy 1 byte. 

String constants will occupy string length+1. 
Numeric constants will occupy 7 bytes. 



NOTE: When memory space is a consideration* space can be 
saved by changing frequently used constants to 
variables. 



Direct mode - The statement has no line number and 

is executed as soon as it is syntaxed. 

Deferred mode - The statement has a line number. It 

is syntaxed on entry* stored* and then 
executed only when the user types RUN. 



All of Basic's statements can be executed either in direct 
or deferred modes. Some have little or no meaning in one mode 
or the other. Others may have unexpected meanings. For 
example: 

In deferred mode: 



DEFERRED AND DIRECT MODES 



There are two modes of execution for statements. 



6000 RUN 



is equivalent to encountering END and 
then the user typing RUN. 



6000 CONT 



has no effect. 



6000 NEW 



is equivalent to encountering END and 
then the user typing NEW. 



In direct mode: 



DATA 
REM 
END 
STOP 



have no meaning and cause no action 
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GOTO 



starts or restarts program execution 
at the line number noted in the GOTO 
statement. 



GOSUD 



calls the subroutine at the given line 
number; Upon RETURN control returns to 
direct mode statements. 



STATEMENT SAVE AREA 



The statements a user has entered and other needed infor- 
mation is stored starting at a lou memory address and 
growing towards high memory. 

This lomem address can be changed with the LQMEM command. 
This can be used in order to reserve space for a USR function. 

The high memory address can be changed using the POKE statement. 
(See the memory map for the location). 



Arrays are one or two dimemsional. Either dimension may 
have the value O to 32767. (Total space is limited by memory 
space). Elements are numbered from zero. 



ARRAYS 



Ex amp le: 



DIM A(3) Allocates 4 elements. 
A(O), A(l), A(2), AO) 



DIM B(l>2) Allocates 6 elements. 
B(0,0>, B(0,1), B(0,2> 
B(1,0), B(l,l), B(l,2) 



An array must be DIMed before it can be used. 
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STRINGS 



A string may have a length of up to 32# 767 characters. 
When a string is DIMensioned, space is allocated for the 
string and its maximum length is fixed. The characters in 
a string are numbered from 1 to the DIMensioned maximum. 

A string must be Dimensioned before it can be used. 



SUBSTRINGS: 



A destination string is one that is being assigned to. 

Any other string is a source string. In 

X*«Y* 

X* is the destination string, Y* is the source string. 
Substrings are defined as follows: 

STRING definition when definition when 

destination string source string 

S* the entire string from 1st thru LEN 

1 thru DIM value character 

S*(n) from nth thru from nth thru 

DIMth character LENgth character 

S*(n>m) from the nth thru from the nth thru 

the mth character the mth character 



It is an error if either the first or last specified 
character (n and m. above) is outside the DIMensioned size. 
It is an error if the last character position given 
(explicitly or implicitly) is less than the first character 
position. 

Example: Assume: DIM A*<10) 

A* ■ "VWXYZ" 

1) PRINT A*<2) prints: 
WXYZ 



2) PRINT A*(3, 4) prints: 
XY 

3) PRINT A*<5, 5) prints: 
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z 

4) PRINT A*(7) 

is an error because A* has a length of 5. 

CONCATENATION 

Example: Assume: DIM A*<5>, B*<5), C*(15) 

A$= "12345 " 
B*="XYZ" 

Then concatenation may be performed 
as follows: 

LET C*=A* 

LET C*(LEN<C*)+1 )=B* 
Now: PRINT C* will produce 

12345XYZ 

(This is equivalant to the C*=A*+B* 
found in some basics). 
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OPERATORS 



PRECEDENCE 

The following order of precedence mill be used when evaluating 
expressions. Operators on the same line have equal precedence. 

< O >■=>■= <> When used with strings 
+ - NOT unary operators 

* means a number raised to a power 

* / 

+ - When used as binary operators. 

< O > => = <> When used for arithmetic comparsions. 

AND 
OR 

Precedence may be overridden by parentheses. 

No binary operator may have both a numeric and string operand. 

Example X=A*=C*>B is valid because it is evaluated 

as X»(A*=C*)>B 

X»A*=<C*>B> is invalid 

AND. NOT, OR 

AND A logical operator which requires both the left and 

right arguments to be true for the statement to be true. 

NOT A logical operator which reverses the truth of the 

argument following it. 

OR A logical operator which requires either the left 

or right argument to be true for the statement to 
be true. 
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NUMBERS 



All numbers in Basic are in BCD floating point. 
RANGE: 

Floating point numbers must be less than 10E+98 and 
greater than or equal to -10E-98. 

INTERNAL FORMAT: 

Numbers are represented internally in 6 bytes. There is a 5 
byte mantissa containing 10 BCD digits and a one byte exponent. 

The most significant bit of the exponent byte gives the sign 
of the mantissa (0 for postive* 1 for negative). The least 
significant 7 bits of the exponent byte gives the exponent in 
excess 64 notation. Internally* the exponent represents powers 
of 100 (not powers of 10). 

Example: 0. 02 = 2 * 10^-2 = 2 * 100^-1 

exponent^ -1 + 40 * 3F 

0. 02 - 3F 02 00 00 00 00 

The implied decimal point is always to the right of the first 
byte. An exponent less than hex 40 indicates a number less 
than 1. An exponent greater than or equal to hex 40 represents 
a number greater than or equal to 1. 

Zero is represented by a zero mantissa and a zero exponent. 
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USR FUNCTION 



The USR function allows the user to execute machine language 
subroutines. The arguments of the USR function are the 
address of the subroutine and any parameters the user wishes 
to pass it (up to 235). The user may return a value in FRO 
8c FRO+1 (see system memory map). In fact. Basic assumes that 
whatever is in FRO is the return value of the function. 

Basic uses the CPU stack to pass the parameters to the 
subroutine. The count of the number of parameters is 
passed in the accumulator. The parameters are each 2 byte 
integers. When the subroutine gets control it must pull 
the information off the stack. 

The first byte on the CPU stack is the MSB of the 1st 
parameter. The second byte is the LSB of the 1st parameter. 
The third byte is the MSB of the 2nd parameter, etc. . . 



Examp 1 e : 



A=USR ( 5000, 200, 300) 



The user routine is at the address 
5000 (hex 1388). 

When the subroutine gets control the 
stack looks as follows. 



Top Of Stack 
(last on) 



00 
C8 



> parm 1 
> 



01 
2C 



> parm 2 

> 



The A register will contain the number of parms 
(02). 

When the user is ready to return, he puts a return value in 
FRO and FRO+l. FRO is the LSB and FRO+1 is the MSB. Then 
he executes a RTS. 

CAUTION: ALL PARAMETERS THAT BASIC PUT ON THE 

STACK MUST BE PULLED OFF PRIOR TO THE 
RTS. The results are totaly unpredict- 
able if this is not done correctly. 

When Basic regains control it takes the 2 byte value in FRO as 
the function's return value. 



The user can reserve space for his USR function by using the 
LOMEM command to increase lomem (the address where Basic 
starts the tables its needs). The user can also reserve space 
by using POKE to change the high memory address (see memory map). 

The user could also put his 6502 code into a DATA statement, 
READ the data, put it into a string with CHR* or POKE and 
then call the USR function with the address of the string. 
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Example: The following program will call the 

Apple II(R) to clear the screen in 
text mode. This is not the best way 
of clearing the screen, but it 
illustrates the use of a string in 
calling a USR function. 

1000 DIM A*(20) 
2000 FOR I ■ 1 TO 4 
3000 READ X 
4000 A*<I) = CHR*(X) 
5000 NEXT I 

6000 A-USR<ADR(A*(1)>) 
7000 DATA 32,88,252,96 

Where the program represented in the DATA statement is: 

20 58 FC JSR *FC5B J JUMP TO SUBROUTINE 

60 RTS } RETURN 

Example: A better way to clear the screen 

would be to call the routine directly. 

100 A=USR< 64600) 

Where 64600 = 65536-936 (FC58 hex). 



NOTE: The "A" in these examples is a dummy variable 
used to take care of the fact that a function 
expects a return value. 



-27- 



INTERFACING TO GRAPHICS 



The Apple IKR) graphics routines are not directly accessible to 
the Basic user, but they can be used by means of POKE and the USR 
function. The following are some examples for low resolution 
graphics. They are not meant to constitute a complete interface. 



To set graphics mode: 



POKE 49232,0 
POKE 49235, 

To set text mode: 

POKE 49233, 



< 49232 -hex C050) 
(49235 -hex C053) 



(49233 m hex C051 ) 



POKE address for other graphics modes can be found in the 
APPLE IKR) reference manual. 

To plot a point: 

Pass the X & Y values to a USR function which will do 
set-up and call the APPLE IKR) graphics routines. 



Examp 1 e: 



Basic program required to plot a point 
at X=5, Y»10. 

100 LOMEM 8192 : REM SAVE SPACE FOR POM 
200 POKE 34,20 : REM SET WINDOW 
300 POKE 49232,0 : REM SET GR MODE 
400 POKE 49235,0 

500 A-USR(4096, 5, 10) : REM CALL FUNCTION 



The USR function calls a routine at 4096 (hex 1000). 
The "A" is a dummy variable used to take care of the 
fact that a function expects a return value. 



Examp le: 



the 6502 code required to interface 
to plot. 



PLOT 



PL0T1 



*«*1000 
PHA 

JSR 
LDA 
STA 
JSR 
PLA 

CMP 
BNE 
PLA 
PLA 
TAY 
PLA 
PLA 



♦F832 
#«FF 
♦30 
♦FC58 



#2 

OOPS 



ORIGIN AT 1000 HEX 
SAVE COUNT 

CLEAR GRAPHICS AREA 
SET COLOR 15 
SET IN COLOR REG 
CLEAR TEXT AREA 
PULL « OF PARMS 
FROM STACK 
SHOULD = 2 
IF NOT ERROR 

GET PARM 1 (X) 
PUT IN Y FOR PLOT 

GET PARM 2 (Y) 
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JSR *F800 i GO TO PLOT 

RTS 

OOPS 

<HANDLE ERRORS HERE> 



This routine will plot in color 15. Calling at PLOT 
initialzes for plotting and plots. Calling at PL0T1 
will do subsequent plots. To plot in various colors 
the routine could be changed to expect the USR function 
to also pass a color. 

NOTE: This routine is meant to serve as an example 
of what might be done* and is not complete. 
For example* the user needs to handle errors 
such as X and Y being out of range. 

NOTE: The color must be set after graphics has been 
initialized. 
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ERROR PROCESSING 



There are two different tgpe of errors in Basic. A syntax 
error can occur when a statement is entered. An execution 
error can occur when the statement is actually executed. 

SYNTAX ERRORS 



A syntax error indicates that the statement just entered is 
not in proper format. Its occurrence causes the line to be 
reprinted on the screen with the word ERROR-. The point at 
which the error was detected (not necessarily the actual error) 
is marked with an inverse video character. 

A syntax error may occur in either direct or deferred mode. 

Example 1) 1000 A«A*+B 

causes: 

1000 ERROR- A=A*+B 



2) A=A*+B 
causes: 



ERROR- A«A*+B 



3) 1000 FOR I - ATOB STEP C 
causes: 

1000 ERROR- FOR I ■ ATOB STEP C 



Where underscore (-) indicates the character in inverse 
video. 

NOTE: In example 3 the error may be that the user 
meant to type 

1000 FOR I « A TO B STEP C 

but since ATOB is a valid variable name, no 
error is detected until STEP. 
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EXECUTION ERRORS 



If an error i* detected while a statement is being executed/ 
Basic prints out: 

ERROR- XX 

If the statement had a line number (ie. it was part of a 
program)* Bacis also prints: 

AT LINE nnnn 

XX represents an error number in the range 1 to 255. 

nnnn represents the line number on which the error occured. 

So the two forms are: 

ERROR- XX 

ERROR- XX AT LINE nnnn 

The following section is a decription of errors represented 
by the error number. 

ERROR NUMBER DECRIPTION 



MEMORY FULL 

All avaiable memory has been used. No more statements 
can be entered and no more variables (arithmetic! string 
or array) can be defined. 

VALUE ERROR 

An expression or variable evaluates to an incorrect value. 

Example: An expression that can be converted to a 

two byte integer in the range to 65235 
(hex FFFF) is called for and the given 
expression is either too large or negative. 

A - PEEK(-l) 
DIM B (70000) 

Both these statments will produce a value 
error 



Example: 



Examp le: 



An expression that can be converted to a one 
byte integer in the range to 255 hex(FF) is 
called for and the given expression is too 
large. 

POKE 5000,750 
This statement produces a value error. 
A as SQR(-4) Produces a value error. 



VARIABLE TABLE FULL 
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No more variables can be defined. The maximum number of 
variables is 128. 

STRING LENGTH ERROR 

A character beyond the DIMensioned or current length of a 
string has been accessed. 

Example: 1000 DIM A*(3) 

2000 A*<5) = "A" 

This will produce a string length error at 
line 2000 when the program is RUN. 

READ OUT OF DATA 

A READ statement is executed but we are already at the 
end of the last DATA statement. 

LINE NUMBER TOO BIG 

A line number larger than 32767 was entered. 
INPUT/READ STATEMENT ERROR 

The INPUT or READ statement did not recieve the type of 
data it expected. 

Example: INPUT A 

If the data entered is 12AB then this error 
will result. 

Example: 1000 READ A 

2000 PRINT A 
3000 END 
4000 DATA 12AB 

Running this program will produce this error. 

ARRAY/STRING DIM ERROR 

Example: A string or an array was used before it 

was DIMinsioned. 

Example: A previously DIMensioned string or array 

is DIMensioned again. 

1000 DIM A(10) 
2000 DIM A(10) 

This program produces a DIM error. 
EXPRESSION TOO COMPLEX 

An expression is too complex for Basic to handle. 
The solution is to break the calculation into two or 
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more Basic statements. 

11 - FLOATING POINT OVERFLOW/UNDERFLOW 

The floating point routines have produced a number 
that is either too large or too small. 

12 - LINE NOT FOUND 

The line number required for a GOTO or GOSUB does 
not exist. 

The GOTO may be implied as in. 

1000 IF A=B THEN 500 
The GOTO/GOSUB may be part of an ON statement. 

13 - NO MATCHING FOR 

A NEXT was encountered but there is no information 
about a FOR with the same variable. 

Example: 1000 DIM A<10) 

2000 REM FILL THE ARRAY 
3000 FOR I ■ TO 10 
4000 A(I) = I 
5000 NEXT I 

6000 REM PRINT THE ARRAY 
7000 FOR K = TO 10 
8000 PRINT A(K) 
9000 NEXT I 
10000 END 

Running this program will cause the following output: 


ERROR- 13 AT LINE 9000 

NOTE: Improper use of POP could cause this error. 

14 - LINE TOO LONG 

The line just entered is longer than Basic can handle. 
The solution is to break the line into multiple lines 
by putting fewer statements on a linei or by evaluating 
the expression in multiple statements. 

15 - GOSUB /FOR LINE DELETED 

The line containing the GOSUB or FOR was deleted after 
it was executed but before the RETURN or NEXT was 
executed. 

This can happen if* while running a program* a STOP is 
executed after the GOSUB or FOR, then the line containing 
the GOSUB or FOR is deleted, then the user types CONT 
and the program tries to execute the RETURN or NEXT. 
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Example: 1000 00SUB 2000 

1100 PRINT "RETURNED FROM SUB" 

1200 END 

2000 PRINT "GOT TO SUB " 

2100 STOP 

2200 RETURN 

If this program is run the print out is: 

COT TO SUB 

STOPPED AT LINE 2100 

Now if the user deletes line 1000 and then types CONT 
we get 

ERROR- 15 AT LINE 2200 

16 - BAD RETURN 

A RETURN was encountered but we have no information 
about a GOSUB. 

Example: 1000 PRINT "THIS IS A TEST" 

2000 RETURN 

If this program is run the print out is: 

THIS IS A TEST 

ERROR- 16 AT LINE 2000 

NOTE: improper use of POP could also cause this error. 

17 - EXECUTION OF GARBAGE 

If when entering a program line a syntax error occurs* 
the line is saved with an indication that it is in 
error. If the program is run without this line 
being corrected, execution of the line will cause 
this error. 

NOTE: The saving of a line that contains a syntax 

error can be useful when LISTing and ENTERing 
programs. 

18 - STRING DOES NOT START WITH A VALID NUMBER 

If when executing the VAL function, the string argument 
does not start with a number, this message number is 
generated. 

Example: A « VALCABC") produces this error. 

19 - LOAD PROGRAM TOO BIG 

The program that the user is trying to LOAD is larger 
than available memory. 
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This could happen if the user had used LOMEM to change 
the address at which Basic tables start* or if he is 
LOADing on a machine with less memory than the one on 
which the program was SAVEd. 

20 - INVALID DEVICE /FILE NUMBER 

If the device/file number given in an I/O statement is 
or greater than 7, then this error is issued. 

Example: GET «8> A 

PUT #0, B+7 

Both of these statements will produce this error. 

21 - NOT A LOAD FILE 

This error results if the user tries to LOAD a file 
that was not created by SAVE. 
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ERROR TRAPPING 



The TRAP statement allows the user to specify the line number 
of a routine that will be executed when an error is encountered. 

Basic saves the error number and the line number where the error 
occured for the user. (See memory map for locations). By doing 
a PEEK the user can see what the error was and determine what 
action he wishes to take. For example if the error was end-of-fil 
he may wish to close the file and end the program. 



The user can return control to the first line (not statement) 
after the statement that caused the error by doing a CONT. 



The user can also return to the first statement of the line 
that caused the error. To do this he must use PEEK to get the 
line number then construct a variable containing that line 
number. 



Examp 1 e 



Assume the memory map says that the 
line number is at location X (in decimal). 
The error routine can return control to 
the 1st statement of the line causing 
the error by saying: 



1000 GOTO PEEK(X)+PEEK(X+1 >«256 



NOTE: 



The TRAP statement must be executed 
before the error occures. 

TRAP may be disabled by using a line number 
greater than 32768. 



NOTE: 



TRAP 40000 



NOTE: 



To prevent infinite loopingi TRAP is 
disabled after an error. If the user 
wants an error routine to be called on 
the next error* he must re-execute TRAP. 
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NOTES 



DEFAULT FILE NUMBER : 

Some Basic commands do not specify a file number but request I/O 
to or from a device other than the screen or keyboard (SAVE* ENTER » 
etc). Basic must have a file number to do this* and it uses file 
number 7. The user should not have this file number assigned to a 
device/file when this type of command is issued. 

ENTERING FROM A PROGRAM 

ENTER can be executed from a program. This causes the statements in 
the file to be merged with the statements in memory. The ENTERed 
statements are not automatically executed. If the user wishes to 
ENTER and then execute, he may append a GOTO statement (without 
a line number) to his file. (See Disk File Manager documentation). 

LOMEM/HIMEM 

A default low memory address is set when the system is booted up. 
Basic does NOT automatically reset this value. If a program (for 
example- a device handler)* sets lomem and then BASIC is entered* 
this address remains unchanged. 

Basic does set a default himem which can be changed by POKE. 
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MEMORY MAP 



The following are memory locations used by OSS. For locations 
uttd by Apple IKR) monitor/ see Apple 1 1 (R ) Reference Manual. 



HEX ADDRESS 



USED FOR 



OOOO- 
0020- 
0050- 
0060- 
0080- 
00D4- 
0100- 
0200- 



00 IF 
•004F 
•005F 
■007F 
•00D3 
•OOFF 
•01FF 
•02FF 



0300-037F 
03F0-03F4 



Reserved for user 
Apple IKR) monitor 
Reserved for user 
OSS Operating System 
Basic 

Floating Point work area 
6502 stack 

Apple IKR) input buffer 
and Basic syntax stack 
Basic line buffer 
Autostart Rom 



Specific locations that may be of interest: 

BA-BB Stop line number (after STOP. END or error) 

C3 Error number 

D4-D9 Floating Point register zero (FRO) 



8000 Basic cold start address 

8003 Basic warm start address 

9FFC-9FFD Pointer to test for escape key 

BFF6-BFF7 Pointer to low memory address 

BFF8-BFF9 Pointer to high memory address 
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SYNTAX SUMMARY 

STATEMENTS 



BYE 

CLOSE #fn 

CLR 

CQNT 

CP 

DATA ASCII characters C, ASCII characters. ... 3 
DEG 

DIM svar (aexp) 

DIM mvar (aexp) 

DIM mvar (aexp. aexp) 

END 

ENTER filspc 

FOR avar ■ aexpl TO aexp2 [STEP aexp33 

GET #fn, avar 

OOSUB linenum 
IF aexp THEN {statement} 

{linenum > 
INPUT C#fn , 3 var C, var. . . 3 
CLETD svar ■ sexp 
CLET} {avar> ■ aexp 

{mvar} 
LIST CfilspcD 

LIST Cfilspc, 3 linenum C, linenum] 
LOAD filspc 
LOMEM address 
NEW 

NEXT avar 

NOTE #fn, {avar>, {avar} 

{mvar} {mvar} 
ON aexp {GOTO } linenum Z, linenum. .. 3 

{OOSUB} 

OPEN #fn» modei aexp* filspc 
POINT #fn, {avar}, {avar} 
{mvar}, {mvar} 
POKE address, aexp 
POP 

PRINT C#fn {i}3 exp C{, } exp. . . 3 {, } 
{, } {j} {j } 

PUT #fn, aexp 

RAD 

READ asvar Z, asvar. . . 3 
REM ASCII characters 

RESTORE C linenum] 
RETURN 

RUN Cfilspc] 
SAVE filspc 
STATUS #fn, {avar} 
{mvar} 

STOP 

TRAP linenum 

XIO cmd, #fn, aexp, aexp, filspc, C,filspc3 
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FUNCTIONS 



ABS<aexp ) 

ADR<»var ) 

ASC<sexp > 

ATN(aexp) 

CHR*(aexp ) 

CLOG(aexp ) 

COS<aexp ) 

EXP(aexp) 

FRE(aexp > 

INT(aexp) 

LEN(sexp) 

LOO(aexp) 

PEEK(addresB) 

RND(aaxp) 

SGN(aexp) 

SIN(aexp ) 

STR*<saxp> 

SQR(aexp) 

USR(address C> parameters. 
VAL(sexp) 



ERROR SUMMARY 



A more detailed explaination of the Basic errors can be found 
in the section on ERROR PROCESSING. 



BASIC ERRORS 



•3 

B. 






r» 
w 




l/AI UP PRRHR 


4 




VARIABLE TABLE FULL 


5 




STRING LENGTH ERROR 


6 




READ OUT OF DATA 


7 




LINE NUMBER TOO BIG 


8 




INPUT/READ STATEMENT ERROR 


9 




ARRAY/STRING DIM ERROR 


10 




EXPRESSION TOO COMPLEX 


11 




FLOATING POINT OVERFLOW/UNDERFLOW 


12 




LINE NOT FOUND 


13 




NO MATCHING FOR 


14 




LINE TOO LONG 


15 




GOSUB/FOR LINE DELETED 


16 




BAD RETURN 


17 




EXECUTION OF GARBAGE 


18 




STRING DOES NOT START WITH VALID NUMBER 


19 




LOAD PROGRAM TOO BIG 


20 




INVALID DEVICE /FILE NUMBER 


21 




NOT A LOAD FILE 
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For the user convenience a summary of the error messages that 
can be generated by DFM/OS and passed to Basic are included. 



DFM/OS ERRORS: 



npp 


nc a 




MCCCACC 
ncSsnvC 




/P1 ) 




HPUTTC KldT DCAnV 
i/CVAV>C IMU I RCnUT 




\ OK / 




K1DK1 pyTPTFWT nPUTTF 
PfwlM LA 1 I CIN 1 i/UVXWCL 


A t2 X 


\ DO / 




HAT A CDDHD 


X w» 


< PA } 






X JJ 


f RS } 
\ w *J I 






X w*t 


\ DO / 




tkiwai in inro Ml IMP PR 




f P7 % 
\ D / / 




LIB T TP PRflTPPT 


X wO 


f pa \ 

\ Do / 




CKin np pti p 

CnlU Ur r* 1LC 


X ou 


I AO ) 




np t up a PRRrtR 


X O 1 


\nl > 




Tnn MAKIV flDCW C T 1 PC /Kin CETfTnD Dl ICTCCD AUATASI CM 


162 


(A2) 




MEDIUM FULL (NO FREE SECTORS) 


163 


<A3) 




FATAL SYSTEM DATA I/O ERROR 


164 


(A4) 




FILE # MISMATCH 


169 


(A5) 




FILE NAME ERROR 


166 


(A6) 




POINT DATA LENGTH ERROR 


167 


(A7> 




FILE PROTECTED 


168 


(A8) 




COMMAND INVALID (SPECIAL OPERATION CODE) 


169 


(A9) 




DIRECTORY FULL 


170 


(AA) 




FILE NOT FOUND 


171 


(AB) 




POINT INVALID 
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